Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

CDGetCodecInfo

Your component receives the CDGetCodecInfo request whenever an application calls the Image Compression Manager's GetCodecInfo function.

pascal ComponentResult CDGetCodecInfo (CodecInfo *info);


info

Contains a pointer to the compressor information structure (defined by the CodecInfo data type) to update. Your component should report its capabilities by formatting a compressor information structure in the location specified by this parameter.

CDGetMaxCompressionSize

Your component receives the CDGetMaxCompressionSize request whenever an application calls the Image Compression Manager's GetMaxCompressionSize function. The caller uses this function to determine the maximum size the data will become for a given parameter.

pascal ComponentResult CDGetMaxCompressionSize (PixMapHandle src,
                                          const Rect *srcRect,
                                          short depth,
                                          CodecQ quality,
                                          long *size);


src

Contains a handle to the source image. The source image is stored in a pixel map structure. Applications use the size information you return to allocate buffers that may be used for more than one image. Consequently, your compressor should not consider the contents of the image when determining the maximum compressed size. Rather, you should consider only the quality level, pixel depth, and image size.

This parameter may be set to nil . In this case the application has not supplied a source image--your component should use the other parameters to determine the characteristics of the image to be compressed.

srcRect

Contains a pointer to a rectangle defining the portion of the source image to compress.

depth

Specifies the depth at which the image is to be compressed. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.

quality

Specifies the desired compressed image quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.

size

Contains a pointer to a field to receive the maximum size, in bytes, of the compressed image.

CDGetCompressionTime

Your component receives the CDGetCompressionTime request whenever an application calls the Image Compression Manager's GetCompressionTime function.

pascal ComponentResult CDGetCompressionTime (PixMapHandle src,
                                         const Rect *srcRect,
                                         short depth, CodecQ
                                         *spatialQuality,
                                         CodecQ *temporalQuality,
                                         unsigned long *time);


src

Contains a handle to the source image. The source image is stored in a pixel map. Applications may use the time information you return for more than one image. Consequently, your compressor should not consider the contents of the image when determining the maximum compression time. Rather, you should consider only the quality level, pixel depth, and image size.

This parameter may be set to nil . In this case the application has not supplied a source image--your component should use the other parameters to determine the characteristics of the image to be compressed.

srcRect

Contains a pointer to a rectangle defining the portion of the source image to compress.

depth

Specifies the depth at which the image is to be compressed. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.

spatialQuality

Contains a pointer to a field containing the desired compressed image quality. The compressor sets this field to the closest actual quality that it can achieve. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values. Check to see if the value of this field is nil and, if so, do not write to location 0.

temporalQuality

Contains a pointer to a field containing the desired sequence temporal quality. The compressor sets this field to the closest actual quality that it can achieve. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values. Check to see if the value of this field is nil and, if so, do not write to location 0.

time

Contains a pointer to a field to receive the compression time, in milliseconds. If your component cannot determine the amount of time required to compress the image, set this field to 0. Check to see if the value of this field is nil and, if so, do not write to location 0.

CDGetSimilarity

Your component receives the CDGetSimilarity request whenever an application calls the Image Compression Manager's GetSimilarity function. Your component compares the specified compressed image to a picture stored in a pixel map and returns a value indicating the relative similarity of the two images.

The CDGetSimilarity function is optional. If your component doesn't support it, it should return the codecUnimpError result code.

pascal ComponentResult CDGetSimilarity (PixMapHandle src,
                                         const Rect *srcRect,
                                          ImageDescriptionHandle desc,
                                         Ptr data,
                                         Fixed *similarity);


src

Contains a handle to the noncompressed image. The image is stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compare to the compressed image.

desc

Contains a handle to the image description structure that defines the compressed image for the operation.

data

Contains a pointer to the compressed image data.

similarity

Contains a pointer to a field that is to receive the similarity value. Your component sets this field to reflect the relative similarity of the two images. Valid values range from 0 (key frame) to 1 (identical).

CDGetCompressedImageSize

Your component receives the CDGetCompressedImageSize request whenever an application calls the Image Compression Manager's GetCompressedImageSize function.

You can use the CDGetCompressedImageSize function when you are extracting a single image from a sequence; therefore, you don't have an image description structure and don't know the exact size of one frame. In this case, the Image Compression Manager calls the component to determine the size of the data.

pascal ComponentResult CDGetCompressedImageSize
                                         (ImageDescriptionHandle desc,
                                          Ptr data, long bufferSize,
                                          DataProcRecordPtr dataProc,
                                          long *dataSize);


desc

Contains a handle to the image description structure that defines the compressed image for the operation.

data

Points to the compressed image data.

bufferSize

Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If the application did not specify a data-loading function this parameter is nil .

dataProc

Points to a data-loading function structure. If the data stream is not all in memory when the application calls GetCompressedImageSize , your component may call an application function that loads more compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-loading functions). This parameter contains a pointer to a structure that identifies the data-loading function. If the application did not provide a data-loading function, this parameter is nil . In this case, the entire image must be in memory at the location specified by the data parameter.

dataSize

Contains a pointer to a field that is to receive the size, in bytes, of the compressed image.

CDTrimImage

Your component receives the CDTrimImage request whenever an application calls the TrimImage function. Your component adjusts a compressed image to the boundaries defined by a rectangle specified by your application. The resulting image data is still compressed and is in the same compression format as the source image.

The CDTrimImage function is optional. If your component doesn't support it, it should return the codecUnimpError result code.

pascal ComponentResult CDTrimImage
                                         (ImageDescriptionHandle desc, Ptr inData,
                                          long inBufferSize, DataProcRecordPtr dataProc,
                                          Ptr outData, long outBufferSize,
                                          FlushProcRecordPtr flushProc, Rect *trimRect,
                                          ProgressProcRecordPtr progressProc);


desc

Contains a handle to the image description structure that describes the compressed image. Your component updates this image description to refer to the resized image.

inData

Points to the compressed image data. If the entire compressed image cannot be stored at this location, the application may provide a data-loading function (see the description of the dataProc parameter to this function for details). This is a 32-bit clean address.

inBufferSize

Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If the application did not specify a data-loading function, this parameter is nil .

dataProc

Points to a data-loading function structure. If the data stream is not all in memory when the application calls the Image Compression Manager's GetCompressedImageSize function, your component may call an application function that loads more compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-loading functions). This parameter contains a pointer to a structure that identifies the data-loading function. If the application did not provide a data-loading function, this parameter is nil . In this case, the entire image must be in memory at the location specified by the inData parameter.

outData

Points to a buffer to receive the trimmed image. If there is not sufficient memory to store the compressed image, the application may choose to write the compressed data to mass storage during the compression operation. The flushProc parameter identifies the data-unloading function. This is a 32-bit clean address.

Your component should place the actual size of the resulting image into the dataSize field of the image description referred to by the desc parameter.

outBufferSize

Specifies the size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If the application did not specify a data-unloading function, this parameter is nil .

flushProc

Points to a data-unloading function structure. If there is not enough memory to store the compressed image, your component may call an application function that unloads some of the compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-unloading functions). This parameter contains a pointer to a structure that identifies that data-unloading function. If the application did not provide a data-unloading function, this parameter is nil . In this case, your component writes the entire compressed image into the memory location specified by the outData parameter.

trimRect

Contains a pointer to a rectangle that defines the desired image dimensions. Your component adjusts the rectangle values so that they refer to the same rectangle in the resulting image (this is necessary whenever data is removed from the beginning of the image).

progressProc

Points to a progress function structure. During the operation, your component should occasionally call an application function to report its progress (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about progress functions). This parameter contains a pointer to a structure that identifies that progress function. If the application did not provide a progress function, this parameter is nil .

CDCodecBusy

Your component receives the CDCodecBusy request whenever an application calls the CDSequenceBusy function. Your component must report whether it is performing an asynchronous operation.

pascal ComponentResult CDCodecBusy (ImageSequence seq);


seq

Contains the unique sequence identifier assigned by the Image Compression Manager's CompressSequenceBegin or DecompressSequenceBegin function.